package ks.client.interfaces;

import java.util.Properties;

/**
 * Outgoing interface that respective clients must provide to properly integrate
 * with the Game Manager.
 * <p>
 * This means that my code expects to call the following methods on code that
 * you write. Together these methods represent the needed behavior on the 
 * client that communicates to the server. 
 * 
 * @author George Heineman
 */
public interface IGameInterface {

	/**
	 * Request by the current user to make a table chat message on the table.
	 * <p>
	 * Note that there is no need to include the player here because that is 
	 * determined by the server.
	 * 
	 * @param tableID   current Table on which player is active
	 * @param text      text to be posted
	 */
	void sendTableChat (int tableID, String text);
	
	/**
	 * For solitaire games, the score is updated a fixed number of seconds
	 * if the score changes. If the timer "minor tick" happens and no score
	 * has been changed, then nothing is sent along to the server.
	 * <p>
	 * If the solitaire game (on the client side) has run out of time, then 
	 * complete is set to <code>true</code>. Note that if complete it is up
	 * to your client to properly send the <b>turn</b> message that encodes
	 * the final information from the point of view of this client.
	 * <p>
	 * Not yet sure how extensive the game-specific information is to be used.
	 * I'm almost ready to eliminate it.
	 * 
	 * @param tableID   table on which game is being played.
	 * @param game      game-specific information about the game status.
	 * @param score     score of the player
	 * 
	 * @param complete  <code>true</code> if the game is over
	 */
	void update (int tableID, int score, String game, boolean complete);
	
	/**
	 * If player decides to close game window (and thereby exit the game early)
	 * this method is called.
	 * 
	 * @param tableID
	 */
	void leaveGame (int tableID);
	
	/**
	 * When player makes turn, this method is invoked.
	 * <p>
	 * scores is a {@link Properties} object where key is the playerID and value
	 * is a string representing that player's score.
	 * <p>
	 * move is a string encoding info about the move that can be interpreted
	 * at other clients but not by the server.
	 * 
	 * @param tableID   The table on which game is being played
	 * @param scores    updates to all player scores.
	 * @param move      opaque-string only known to other gamewindows
	 * @param complete  Is this the final move?
	 */
	void turn (int tableID, Properties scores, String move, boolean complete);

	/**
	 * When player makes turn, this method is invoked.
	 * <p>
	 *  
	 * @param tableID   The table on which game is being played
	 */
	void skip(int tableID);
}
